|
|
ContextualMenuSelect |
||||
| Header: | Menus.h | Carbon status: | Supported | |
Displays a contextual menu.
OSStatus ContextualMenuSelect (
MenuHandle inMenu,
Point inGlobalLocation,
Boolean inReserved,
UInt32 inHelpType,
ConstStr255Param inHelpItemString,
const AEDesc *inSelection,
UInt32 *outUserSelectionType,
SInt16 *outMenuID,
UInt16 *outMenuItem
);
A handle to a menu containing application commands to display. The caller creates this menu based on the current context, the mouse location, and the current selection (if it was the target of the mouse). If you pass nil, only system commands will be displayed. The menu should be added to the menu list as a pop-up menu (using the InsertMenu function).
The location (in global coordinates) of the mouse near which the menu is to be displayed.
Reserved for future use. Pass false for this parameter.
An identifier specifying the type of help to be provided by the application; see
The string containing the text to be displayed for the help menu item. This string is unused unless you also pass the constant kCMOtherHelp in the inHelpType parameter.
A pointer to an object specifier for the current selection. This allows the system to examine the selection and add special system commands accordingly. Passing a value of nil indicates that no selection should be examined, and most likely, no special system actions will be included.
A pointer to an unsigned 32-bit value. On return, the value indicates what the user selected from the contextual menu; see
A pointer to a signed 16-bit value. On return, if outUserSelectionType is set to kCMMenuItemSelected, the value is set to the menu ID of the chosen item.
A pointer to an unsigned 16-bit value. On return, if outUserSelectionType is set to kCMMenuItemSelected, the value is set to the menu item chosen.
A result code. ContextualMenuSelect returns the result code userCanceledErr and sets outUserSelectionType to kCMNothingSelected to indicate that the user did not select anything from the contextual menu and no further processing is needed.
If the IsShowContextualMenuClick function returns true, you should call the ContextualMenuSelect function after generating your own menu and preparing an Apple Event descriptor (AEDesc) that describes the item for which your application is displaying a contextual menu. This descriptor may contain an object specifier or raw data and will be passed to all contextual menu plug-ins.
The system will add other items before displaying the contextual menu, and it will remove those items before returning, leaving the menu in its original state.
After all the system commands are added, the contextual menu is displayed and tracked. If the user selects one of the system items, it is handled by the system and the call returns as though the user didn’t select anything from the menu. If the user selects any other item (or no item at all), the Menu Manager passes back appropriate values in the parameters outUserSelectionType, outMenuID, and outMenuItem.
Your application should provide visual feedback indicating the item that was clicked upon. For example, a click on an icon should highlight the icon, while a click on editable text should not eliminate the current selection.
If the outUserSelectionType parameter contains kCMMenuItemSelected, you should look at the outMenuID and outMenuItem parameters to determine what menu item the user chose and handle it appropriately. If the user selected kCMHelpItemSelected, you should open the proper Apple Guide sequence or other form of custom help.
See also
This function is available with Appearance Manager 1.0 and later.
Supported in Carbon. Available in CarbonLib 1.0 and later when ContextualMenu 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by ContextualMenu 1.0 and later.
© 2000 Apple Computer, Inc. — (Last Updated 4/14/2000)